/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.transaction.interceptor;

import java.lang.reflect.Method;

import org.springframework.lang.Nullable;

/**
 * Strategy interface used by {@link TransactionInterceptor} for metadata retrieval.
 *
 * <p>Implementations know how to source transaction attributes, whether from configuration,
 * metadata attributes at source level (such as Java 5 annotations), or anywhere else.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @since 15.04.2003
 * @see TransactionInterceptor#setTransactionAttributeSource
 * @see TransactionProxyFactoryBean#setTransactionAttributeSource
 * @see org.springframework.transaction.annotation.AnnotationTransactionAttributeSource
 */
/*
1. 总结
 策略接口，用于定义如何获取方法的事务属性TransactionAttribute对象即@Transactional 注解对象。
	它是 TransactionInterceptor 的关键组件，负责从配置、注解或其他元数据源中检索事务信息。
	提供了灵活的扩展机制，支持基于注解、方法名匹配、配置映射等多种事务属性来源。
2. 内部成员说明
	TransactionAttributeSource 接口包含以下两个方法：
	isCandidateClass(Class<?> targetClass): 判断给定类是否需要进行事务属性检查。返回 false 可以跳过该类的方法遍历，是一种性能优化手段。默认实现返回 true。
	getTransactionAttribute(Method method, Class<?> targetClass): 获取指定方法的事务属性，如果方法不需要事务则返回 null。
3. 类关系结构
	TransactionAttributeSource (interface)
	├── AbstractFallbackTransactionAttributeSource (abstract class)	象基类，提供了默认的事务属性查找逻辑，其他具体实现继承自它。
	│   ├── AnnotationTransactionAttributeSource (class)	最常用的实现，基于 @Transactional 注解获取事务属性。
	│   └── MapTransactionAttributeSource (class)	基于配置的映射表来查找事务属性。它允许通过代码或 XML 配置的方式，将方法名与事务属性进行映射
	├── MatchAlwaysTransactionAttributeSource (class)	总是返回一个固定的事务属性，无论调用哪个方法。这个类通常用于测试或特殊场景。
	├── MethodMapTransactionAttributeSource (class)	通过配置的映射表来查找事务属性。
	├── CompositeTransactionAttributeSource (class)	组合多个 TransactionAttributeSource 实现，提供更灵活的事务属性来源。
	└── NameMatchTransactionAttributeSource (class)	基于方法名匹配规则来确定事务属性。
	相关类和接口关系说明
		AnnotationTransactionAttributeSource: 最常用的实现，基于 @Transactional 注解获取事务属性。
		NameMatchTransactionAttributeSource: 基于方法名匹配规则来确定事务属性。
		MethodMapTransactionAttributeSource: 通过配置的映射表来查找事务属性。
		CompositeTransactionAttributeSource: 组合多个 TransactionAttributeSource 实现，提供更灵活的事务属性来源。
		AbstractFallbackTransactionAttributeSource: 抽象基类，提供了默认的事务属性查找逻辑，其他具体实现继承自它。

4. 使用场景
	在 Spring 事务管理中，配合 TransactionInterceptor 使用
	实现基于注解的事务管理（如 @Transactional）
	配置事务属性的多种方式（注解、XML配置、代码配置等）
	自定义事务属性源的扩展点
5. 实际代码应用示例
	// 配置基于注解的事务管理器
@Configuration
@EnableTransactionManagement
public class TransactionConfig {

    @Bean
    public TransactionAttributeSource transactionAttributeSource() {
        // 使用基于注解的事务属性源
        return new AnnotationTransactionAttributeSource();
    }

    @Bean
    public TransactionInterceptor transactionInterceptor(
            PlatformTransactionManager transactionManager,
            TransactionAttributeSource transactionAttributeSource) {

        TransactionInterceptor interceptor = new TransactionInterceptor();
        interceptor.setTransactionManager(transactionManager);
        interceptor.setTransactionAttributeSource(transactionAttributeSource);
        return interceptor;
    }
}

// 业务类使用事务注解
@Service
public class UserService {

    @Transactional(rollbackFor = Exception.class)
    public void createUser(User user) {
        // 数据库操作
    }

    public void findUser(Long id) {
        // 只读操作，无事务注解
    }
}

 */
public interface TransactionAttributeSource {

	/**
	 * Determine whether the given class is a candidate for transaction attributes
	 * in the metadata format of this {@code TransactionAttributeSource}.
	 * <p>If this method returns {@code false}, the methods on the given class
	 * will not get traversed for {@link #getTransactionAttribute} introspection.
	 * Returning {@code false} is therefore an optimization for non-affected
	 * classes, whereas {@code true} simply means that the class needs to get
	 * fully introspected for each method on the given class individually.
	 * @param targetClass the class to introspect
	 * @return {@code false} if the class is known to have no transaction
	 * attributes at class or method level; {@code true} otherwise. The default
	 * implementation returns {@code true}, leading to regular introspection.
	 * @since 5.2
	 */
	default boolean isCandidateClass(Class<?> targetClass) {
		return true;
	}

	/**
	 * Return the transaction attribute for the given method,
	 * or {@code null} if the method is non-transactional.
	 * @param method the method to introspect
	 * @param targetClass the target class (may be {@code null},
	 * in which case the declaring class of the method must be used)
	 * @return the matching transaction attribute, or {@code null} if none found
	 */
	@Nullable
	TransactionAttribute getTransactionAttribute(Method method, @Nullable Class<?> targetClass);

}
